home *** CD-ROM | disk | FTP | other *** search
/ Just Call Me Internet / Just Call Me Internet.iso / prog / atari / c / eddilib / new_func.txt < prev   
Text File  |  1993-06-21  |  14KB  |  357 lines
  1.                            Enhanced NVDI 2.50 Functions
  2.                            ============================
  3.  
  4.    This document describes the enhanced NVDI 2.50 functions for screen 
  5.    output.
  6.  
  7. 1. Off-Screen Bitmaps
  8. =====================
  9.  
  10.    Sometimes  it's  very  useful  to  perform  drawing operations on hidden 
  11.    screens   and  to  use vro_cpyfm() to transfer the complete image to the 
  12.    screen  - you may want to avoid screen flickering or just cache a screen 
  13.    region, etc.. These hidden screens are called `Off-Screen Bitmaps'.
  14.    You can create off-screen bitmaps by calling OPEN BITMAP. You can either 
  15.    pass  the  size  of a bitmap to v_opnbm() which will allocate memory for 
  16.    it,  or  you  can  pass a pointer to a bitmap you have already allocated 
  17.    memory  for. The bitmap will be in device-specific or monochrome format. 
  18.    Therefore  you  can  copy  raster areas from screen to a bitmap and vice 
  19.    versa without using vr_trnfm(). 
  20.    The function CLOSE BITMAP closes a bitmap created with OPEN BITMAP and - 
  21.    if necessary - frees the memory block.
  22.  
  23.  
  24.       OPEN BITMAP (VDI 100, 1)
  25.  
  26.       void  v_opnbm( WORD *work_in, MFDB *bitmap, WORD *handle, WORD *work_out )
  27.       {
  28.          pb[1] = work_in;
  29.          pb[3] = work_out;
  30.          pb[4] = work_out + 45;
  31.  
  32.          contrl[0] = 100;
  33.          contrl[1] = 0;
  34.          contrl[3] = 20;
  35.          contrl[5] = 1;
  36.          *(MFDB *)&contrl[7] = bitmap;
  37.  
  38.          vdi();
  39.  
  40.          *handle = contrl[6];
  41.          pb[1] = intin;
  42.          pb[3] = intout;
  43.          pb[4] = ptsout;
  44.       }
  45.  
  46.       VDI arrays:
  47.  
  48.        Element          | Content
  49.       ------------------|-------------------------------------------
  50.       contrl[0]         | 100    opcode for v_opnbm()
  51.       contrl[1]         | 0      number of parameters in ptsin
  52.       contrl[2]         | 6      number of parameters in ptsout
  53.       contrl[3]         | 20     number of parameters in intin
  54.       contrl[4]         | 45     number of parameters in intout
  55.       contrl[5]         | 1      sub-opcode for v_opnbm()
  56.       contrl[6]         | handle
  57.       contrl[7..8]      | bitmap pointer to the MFDB of bitmap
  58.                         |
  59.       intin[0..19]      | work_in[0..19]
  60.                         |
  61.       intout[0..44]     | work_out[0..44]
  62.                         |
  63.       ptsout[0..11]     | work_out[45..56]
  64.  
  65.  
  66.       handle:           graf_handle()
  67.  
  68.       work_in[0..10]:   see v_opnwk()/v_opnvwk()
  69.       work_in[0]:       Getrez() + 2
  70.       work_in[11]:      Width -1 (e.g. 1279)
  71.       work_in[12]:      Height -1 (e.g. 959)
  72.       work_in[13]:      Width of a pixel in 1/1000 mm
  73.       work_in[14]:      Height of a pixel in 1/1000 mm
  74.       work_in[15..19]:  reserved, should contain 0
  75.  
  76.       Attention:  Work_in[11]  +  1  should  be  divisible  by  16  without 
  77.                   remainder.  Otherwise  the  VDI  driver  will  round  up  
  78.                   (work_in[11] + 1) to the next number which can be divided 
  79.                   by 16 without remainder.
  80.                   If  pixel  width  and  height are 0 the pixel size of the 
  81.                   screen workstation is used.
  82.  
  83.       work_out[0..1]:   see v_opnwk()/v_opnvwk()
  84.       work_out[2]:      0
  85.       work_out[3..38]:  see v_opnwk()/v_opnvwk()
  86.       work_out[39]      0 (no hardware clut)
  87.       work_out[39..56]: see v_opnwk()/v_opnvwk()
  88.  
  89.       bitmap:           pointer to MFDB
  90.  
  91.       If  bitmap->fd_addr  is  zero,  the  VDI will allocate memory for the 
  92.       bitmap and will clear it (in contrast to v_opnvwk() ). 
  93.  
  94.       To  open a bitmap in device-specific format bitmap->fd_nplanes should 
  95.       be  zero  or  the  number  of  planes of the screen (work_out[4] from 
  96.       vq_extnd()).  If bitmap->fd_nplanes is 1, a monochrome bitmap will be 
  97.       created.
  98.       The   elements   of  the  MFDB  (fd_addr,  fd_w,  fd_h,  fd_wdwidth,  
  99.       fd_stand,fd_nplanes)  are  set  by  the  VDI  before  returning  from 
  100.       v_opnbm().  If  there  is  not  enough  memory to create a bitmap the 
  101.       handle will be zero and the MFDB will not be changed.
  102.  
  103.       If  bitmap->fd_addr  is  not  zero,  it  will be used as pointer to a 
  104.       bitmap.  If  the bitmap is in standard format, it will be transformed 
  105.       into device-specific format. If the number of planes of the bitmap is 
  106.       not supported by the VDI, a zero handle will be returned.
  107.  
  108.  
  109.       CLOSE BITMAP (VDI 101, 1)
  110.  
  111.       void  v_clsbm( WORD handle )
  112.       {
  113.          contrl[0] = 101;
  114.          contrl[1] = 0;
  115.          contrl[3] = 0;
  116.          contrl[5] = 1;
  117.          contrl[6] = handle;
  118.          vdi();
  119.       }
  120.  
  121.       VDI arrays:
  122.  
  123.        Element          | Content
  124.       ------------------|-------------------------------------------
  125.       contrl[0]         | 101    opcode for v_clsbm()
  126.       contrl[1]         | 0      number of parameter in ptsin
  127.       contrl[2]         | 0      number of parameter in ptsout
  128.       contrl[3]         | 0      number of parameter in intin
  129.       contrl[4]         | 0      number of parameter in intout
  130.       contrl[5]         | 1      sub-opcode for v_clsbm()
  131.       contrl[6]         | handle
  132.  
  133.       The  function  v_clsbm() closes the bitmap specified with handle. The 
  134.       memory of the bitmap will be freed if the VDI has allocated it.
  135.  
  136.  
  137.    Raster Operations and Off-Screen Bitmaps:
  138.    =========================================
  139.  
  140.    Raster  operations between screen and a bitmap generally have to be done 
  141.    in device-specific format.
  142.    If a bitmap is the destination of a raster operation, you should use the 
  143.    bitmap's  handle.  Otherwise  vro_cpyfm() or vrt_cpyfm() cannot clip the 
  144.    area they have to copy and may overwrite other applications' memory.
  145.  
  146.    If  you  use  the  handle  of a bitmap created by v_opnbm() for a raster 
  147.    operation  then  a  zero in MFDB->fd_addr is not a pointer to the screen 
  148.    but to the bitmap.
  149.    In  contrast  to  a screen workstation on a bitmap clipping is also done 
  150.    when  MFDB->fd_addr  is  the address of the bitmap returned by v_opnbm() 
  151.    (on  a  screen  workstation  clipping is only done when MFDB->fd_addr is 
  152.    zero).
  153.  
  154.    See also: BITMAP.C
  155.  
  156.    ESCAPES
  157.    -------
  158.    VDI  escape functions can't be used on Off-Screen bitmaps. The calls are 
  159.    ignored.
  160.  
  161.    vs_color()/vq_color()
  162.    ---------------------
  163.    vs_color()  and  vq_color()  can  be used in Hi- or True Color mode on a 
  164.    Off-Screen  bitmap.  Otherwise the calls are ignored (vq_color() returns
  165.    -1 if not used in Hi- or True Color mode).
  166.  
  167.    vst_point()
  168.    -----------
  169.    vst_point()  and  all  other  functions  that  change the text character 
  170.    height  in  printer points won't set the requested character size if the 
  171.    pixel  height  and  width of the screen is different to the pixel height 
  172.    and width of the Off-Screen bitmap.
  173.  
  174.    v_show_c()/v_hide_c()
  175.    ---------------------
  176.    v_show_c() and v_hide_c() can't be used on Off-Screen bitmaps. The calls 
  177.    are ignored.
  178.  
  179.  
  180. 2. vq_scrninfo()
  181. ================
  182.  
  183.    The  funcion  INQUIRE  SCREEN INFORMATION returns additional information 
  184.    about the device-specific screen format.  
  185.    This function is useful for programs which
  186.    -  support Genlock (Overlay)
  187.    -  build  rasters  (also  in  TrueColor)  and  want  to  copy them with 
  188.       vro_cpyfm() to the screen
  189.    -  save rasters (e.g. XIMGs)
  190.  
  191.       VQ_SCRNINFO( 102, 1 )
  192.  
  193.       void  vq_scrninfo( WORD handle, WORD *work_out )
  194.       {
  195.          pb[3] = work_out;
  196.  
  197.          intin[0] = 2;
  198.          contrl[0] = 102;
  199.          contrl[1] = 0;
  200.          contrl[3] = 1;
  201.          contrl[5] = 1;
  202.          contrl[6] = handle;
  203.          
  204.          vdi();
  205.  
  206.          pb[3] = intout;
  207.       }
  208.  
  209.       VDI arrays:
  210.  
  211.        Element          | Content
  212.       ------------------|-------------------------------------------
  213.       contrl[0]         | 102    opcode for vq_scrninfo()
  214.       contrl[1]         | 0      number of parameters in ptsin
  215.       contrl[2]         | 0      number of parameters in ptsout
  216.       contrl[3]         | 1      number of parameters in intin
  217.       contrl[4]         | 272    number of parameters in intout
  218.       contrl[5]         | 1      sub-opcode for vq_scrninfo()
  219.       contrl[6]         | handle
  220.                         |
  221.       intin[0]          | 2      return additional information
  222.                         |
  223.       intout[0..272]    | work_out[0..272]
  224.  
  225.  
  226.       intout[0]:  Device Format
  227.                   0: interleaved planes, word-wide (ATARI graphic)
  228.                   1: whole planes (standard format)
  229.                   2: packed pixels
  230.                  -1: unknown format
  231.       intout[1]:  Supported CLUT:
  232.                   0: no CLUT (e.g. TTM 194)
  233.                   1: hardware CLUT
  234.                   2: software CLUT (HiColor or TrueColor)
  235.       intout[2]:  number of planes (bits) per pixel
  236.       intout[3/4]:number of colors or 0L (more than 2*10^31 colors)
  237.       intout[8]:  number of bits for red intensity
  238.       intout[9]:  number of bits for green intensity
  239.       intout[10]: number of bits for blue intensity
  240.       intout[11]: number of bits for alpha channel
  241.       intout[12]: number of bits for genlock
  242.       intout[13]: number of unused bits
  243.  
  244.       If a CLUT exists:
  245.       intout[16-271]: pixel value of the corresponding VDI color index
  246.  
  247.       HiColor or TrueColor:
  248.       intout[16..31]:   association of bit number in the pixel and bit of 
  249.                         the red intensity
  250.       intout[32..47]:   association of bit number in the pixel and bit of 
  251.                         the green intensity
  252.       intout[48..63]:   association of bit number in the pixel and bit of
  253.                         the blue intensity
  254.       intout[64..79]:   association of bit number for alpha channel
  255.       intout[80..95]:   association of bit numbers for genlock
  256.       intout[96..127]:  bit numbers of unused bits
  257.       intout[128..271]: reserved (0)
  258.  
  259.    Examples:
  260.    ---------
  261.  
  262.       The following output would be done in 256 colors on the Falcon:
  263.  
  264.       intout   | Value  | Meaning
  265.       ---------|--------|-----------------------------------------------------
  266.          0     |   0    | interleaved planes
  267.          1     |   1    | hardware CLUT exists
  268.          2     |   8    | 8 bit per pixel
  269.          3/4   | 256    | 256 colors
  270.          8     |   6    | 6 bits for red intensity
  271.          9     |   6    | 6 bits for green intensity
  272.         10     |   6    | 6 bits for blue intensity
  273.         11     |   0    | no bit for alpha channel
  274.         12     |   0    | no bit for genlock
  275.         13     |   0    | no unused bits
  276.                |        |
  277.                |        |
  278.         16     |   0    | pixel value of VDI color index 0
  279.         17     | 255    | pixel value of VDI color index 1
  280.         18     |   2    | pixel value of VDI color index 2
  281.         ...    | ...    |
  282.        271     |  15    | pixel value of VDI color index 255
  283.  
  284.       The following output would be done in HiColor on the Falcon:
  285.  
  286.       intout   | Value  | Meaning
  287.       ---------|--------|-----------------------------------------------------
  288.          0     |   2    | packed pixels
  289.          1     |   2    | HiColor/TrueColor
  290.          2     |  16    | 16 bit per pixel
  291.          3/4   | 32768  | 32768 colors
  292.          8     |   5    | 5 bits for red intensity
  293.          9     |   5    | 5 bits for green intensity
  294.         10     |   5    | 5 bits for blue intensity
  295.         11     |   0    | no bit for alpha channel
  296.         12     |   1    | 1 bit for genlock
  297.         13     |   0    | no unused bits
  298.                |        |
  299.                |        |
  300.         16     |  11    | bit 0 of the red intensity (least significant bit)
  301.                |        | is in bit 11 of the pixel
  302.         17     |  12    | bit 1 is in bit 12 of the pixel
  303.         18     |  13    | ...
  304.         19     |  14    | ...
  305.         20     |  15    | bit 4 of the red intensity (most significant bit)
  306.                |        | is in bit 15 of the pixel
  307.         21..31 |  -1    | bits are not used for red intensity
  308.                |        |
  309.                |        |
  310.         32     |   6    | bit 0 of the green intensity (least significant bit)
  311.                |        | is in bit 6 of the pixel
  312.         33     |   7    | bit 1 is in bit 7 of the pixel
  313.         34     |   8    | ...
  314.         35     |   9    | ...
  315.         36     |  10    | bit 4 of the green intensity (most significant bit)
  316.                |        | is in bit 10 of the pixel
  317.         37..37 |  -1    | bits are not used for green intensity
  318.                |        |
  319.                |        |
  320.         48     |   0    | bit 0 of the blue intensity (least significant bit)
  321.                |        | is in bit 0 of the pixel
  322.         49     |   1    | bit 1 is in bit 1 of the pixel
  323.         50     |   2    | ...
  324.         51     |   3    | ...
  325.         52     |   4    | bit 4 of the blue intensity (most significant bit)
  326.                |        | is in bit 4 of the pixel
  327.         53..63 |  -1    | bits are not used for blue intensity
  328.                |        |
  329.                |        |
  330.         64..79 |  -1    | no alpha channel
  331.                |        |
  332.                |        |
  333.         80     |   5    | bit for genlock
  334.         81..95 |  -1    | not used for genlock
  335.                |        |
  336.                |        |
  337.         96..127|  -1    | no unused bits
  338.                |        |
  339.                |        |
  340.  
  341.  
  342.  
  343. 3. Recognizing the enhanced VDI functions
  344. =========================================
  345.  
  346.    NVDI  (and  also  the  ENHANCER  for  the ATARI-VDI) will place a 'EdDI' 
  347.    cookie  in  the  cookie jar containing a dispatcher adress in the cookie 
  348.    value.  The dispatcher uses Turbo C/Pure C calling conventions (register 
  349.    d0  contains the opcode; registers d1-d2/a0-a1 and the stack may be used 
  350.    for additional parameters).
  351.  
  352.    Till  now  only  opcode 0 is implemented. This opcode returns the 'EdDI' 
  353.    version  number.
  354.    Version  1.00  (retun  value  is $100) supports v_opnbm(), v_clsbm() and 
  355.    vq_scrninfo().
  356.    
  357.